<!DOCTYPE HTML>
<html>
<head>
<title>ComObjConnect() | AutoHotkey</title>
<meta name="description" content="The ComObjConnect function connects a COM object's event sources to functions with a given prefix." />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<link href="../static/theme.css" rel="stylesheet" type="text/css" />
<script src="../static/content.js" type="text/javascript"></script>
<script type="text/javascript">$(function(){0<=window.navigator.userAgent.toLowerCase().indexOf("ucbrowser")&&CaoNiMaDeUc()})</script>
</head>
<body>

<h1>ComObjConnect() <span class="ver">[AHK_L 53+]</span></h1>
<p>链接 COM 对象的事件到给定的前缀名的响应函数.</p>
<pre class="Syntax"><span class="func">ComObjConnect</span>(ComObject <span class="optional">, Prefix</span>)</pre>

<h2 id="Parameters">参数</h2>
<dl>

  <dt>ComObject</dt>
  <dd>
    <p>产生事件的对象.</p>
    <p>如果对象不支持 IConnectionPointContainer 接口, 或无法获取对象类的类型信息, 将显示一条错误信息. 可通过 <a href="ComObjError.htm">ComObjError()</a> 或 <a href="Try.htm">try</a>/<a href="Catch.htm">catch</a> 禁止或处理此错误信息.</p>
    <p><span class="ver">[v1.1.22+]</span>: 如果对象支持, 使用 IProvideClassInfo 接口以接收此对象类的类型信息. 否则, ComObjConnect 尝试通过对象的 IDispatch 接口以接收类型信息, 这可能不可靠.</p>
  </dd>

  <dt>Prefix</dt>
  <dd>
      <p>用于确定当事件发生时应调用哪个函数, 此字符串为事件名称(EventName) 对应的前缀(Prefix) .</p>
      <p>如果省略, 则对象为 "未连接的"; 即脚本将不再接收其事件通知.</p>
      <p><span class="ver">[v1.1.01+]:</span> 此参数可以为脚本定义的对象. 事件发生时, 会调用相应的方法. 首个参数, 通常为隐式传递的参数 <code>this</code>, 其引用脚本定义的对象, 而非 COM 对象. 要捕获所有事件, 而又不想为每个事件定义方法, 可定义 <a href="../Objects.htm#Meta_Functions">__Call 元函数</a>.</p>
    </dd>

</dl>

<h2 id="Usage">用法</h2>
<p>在脚本中编写处理所需事件的函数. 这类函数或 "事件处理程序" 具有下列结构:</p>
<pre class="Syntax Short NoIndent"><i>Prefix</i><b>EventName</b>([<i>Params...</i>, ComObject])
{
    <i class="dull">... event-handling code ...</i>
    return <i>ReturnValue</i>
}</pre>
<p><i>Prefix(前缀)</i> 为用户定义; 而 <b>EventName(事件名称)</b> 为期望此函数响应的事件名称, 定义于产生事件的对象.</p>
<p><i>Params(参数)</i> 对应于事件包含的所有参数. 如果事件不含有参数, <i>Params</i> 应完全省略. <i>ComObject</i> 为可选, 仅当 <i>Params</i> 的数目正确时; 它包含了到传递给 ComObjConnect 的原始包装器(转换器) 对象的引用. "ComObject"应被替换为与您脚本上下文相关的更有意义的名称.</p>
<p>注意, 事件处理程序可以产生返回值. 要返回特定的 COM 类型的值, 使用 <a href="ComObjActive.htm#param">ComObject(类型, 值)</a>. 例如, <code>return ComObject(0,0)</code> 返回类型为 VT_EMPTY 的变体, 其等效于从 JavaScript 函数中返回 <code>undefined</code>(或未返回).</p>
<p>调用 <code>ComObjConnect(目标对象, "<i>Prefix</i>")</code> 以启用事件处理.</p>
<p>调用 <code>ComObjConnect(目标对象)</code> 以断开对象(停止事件处理).</p>
<p>如果参数的数目未知, 可用<a href="../Functions.htm#Variadic">可变参数函数</a>.</p>

<h2 id="Remarks">备注</h2>
<p>脚本必须保留对 <em>ComObject</em> 的引用, 否则它将自动释放, 并与其 COM 对象断开连接, 从而阻止任何进一步的事件被检测. 没有标准的方法来检测何时不再需要连接, 因此脚本必须通过调用 ComObjConnect 来手动断开连接.</p>
<p>可能需要使用 <a href="_Persistent.htm">#Persistent</a> 指令, 以便在脚本监听事件时保持脚本运行.</p>
<p>失败时, 函数可能会抛出异常, 退出脚本或返回空字符串, 具体取决于当前的 <a href="ComObjError.htm">ComObjError()</a> 设置和<a href="ComObjError.htm#factors">其他因素</a>.</p>

<h2 id="Related">相关</h2>
<p><a href="ComObjCreate.htm">ComObjCreate()</a>, <a href="ComObjGet.htm">ComObjGet()</a>, <a href="ComObjActive.htm">ComObjActive()</a>, <a href="ComObjError.htm">ComObjError()</a>, <a href="http://msdn.microsoft.com/en-us/library/ccxe1xe6.aspx">WScript.ConnectObject (MSDN)</a></p>

<h2 id="Examples">示例</h2>
<div class="ex" id="ExIE">
<p><a class="ex_number" href="#ExIE"></a> 启动 Internet Explorer 的实例, 并将事件连接到相应的前缀为 "IE_" 的脚本函数. 有关 COM 对象和下面使用的 DocumentComplete 事件的详情, 请参阅 <a href="http://msdn.microsoft.com/en-us/library/aa752084.aspx">InternetExplorer object (Microsoft Docs)</a>.</p>
<pre>ie := ComObjCreate("InternetExplorer.Application")

<em>; 把事件连接到带 "IE_" 前缀的脚本函数.</em>
ComObjConnect(ie, "IE_")

ie.Visible := true  <em>; 已知此语句在 IE7 上无法正常执行.</em>
ie.Navigate("https://www.autohotkey.com/")
#Persistent

IE_DocumentComplete(ieEventParam, url, ieFinalParam) {
    global ie
    if (ie != ieEventParam)
        s .= "第一个参数是新的包装器对象.`n"
    if (ie == ieFinalParam)
        s .= "最后一个参数是原始包装器对象.`n"
    if ((disp1:=<a href="ComObjActive.htm#enwrap">ComObjUnwrap</a>(ieEventParam)) == (disp2:=ComObjUnwrap(ieFinalParam)))
        s .= "两个包装器对象均引用同一个 IDispatch 实例.`n"
    <a href="ObjAddRef.htm">ObjRelease</a>(disp1), ObjRelease(disp2)
    MsgBox % s . "完成载入" ie.Document.title " @ " url
    ie.Quit()
    ExitApp
}
</pre>
</div>

</body>
</html>